\manpage intro(1)

\manname
	intro --- introduction to graphics functions
\mandscr

\manhead Using the library\par

	When writing a program that uses the Grafix library, you should
	include the file \bfnc graf.h . This file defines prototypes for
	all the graphics functions and several symbolic constants.
	When linking, simply include the Grafix library in the list
	of libraries you supply to LINK. The small model library
	is named \bfnc grafix.lib , and the medium, compact, and
	large model libraries are named \bfnc grafixm.lib ,
	\bfnc grafixc.lib , and \bfnc grafixl.lib , respectively.

	Note that \itwd g_init must be the first function in the
	library to be called, and that \itwd g_open must be the second.
	When you finish with the graphics display, you should
	call \itwd g_close to reset the display to text mode.

\manhead Supported hardware\par

	The Grafix library currently supports the following graphics
	hardware:

	IBM Color Graphics Adapter (CGA) with a Color Display or equivalents.

	IBM Enhanced Graphics Adapter (EGA) with a Enhanced Graphics Display,
	with a Color Display, or with a Monochrome Display or equivalents.

\manhead Colors\par
	It should be kept in mind that the color values which are passed to
	the graphics
	routines and written into the graphics buffers correspond only
	indirectly to the colors actually displayed on the screen. The
	mapping between color values and displayed colors can
	be changed by the \itwd g_setback and \itwd g_setpal functions.
	See the ``colors(1)'' manual page for a description of the available
	colors.
\manex
\vinput grafex1.c
\manpend

\manpage colors(1)

\manpage colors(1)

\manname
	colors --- summary of displayable colors
\mandscr
	The following summarizes the displayable colors in the
	various supported graphics modes.

\manhead CGA 320 by 200 four color mode\par

	In this mode, color value~0 is the background. By default it
	is black but may be changed by use of the \itwd g_setback function
	to any of the following colors:
\begintable
\centerline{\vbox{%
\settabs\+&\it val&ue\quad&\cr
		\+&\it value&&\it color\cr
		\smallskip
		\+&\hfill 0&& black\cr
		\+&\hfill 1&& blue\cr
		\+&\hfill 2&& green\cr
		\+&\hfill 3&& cyan\cr
		\+&\hfill 4&& red\cr
		\+&\hfill 5&& purple\cr
		\+&\hfill 6&& brown\cr
		\+&\hfill 7&& white\cr
		\+&\hfill 8&& grey\cr
		\+&\hfill 9&& bright blue\cr
		\+&\hfill 10&& bright green\cr
		\+&\hfill 11&& bright cyan\cr
		\+&\hfill 12&& bright red\cr
		\+&\hfill 13&& bright purple\cr
		\+&\hfill 14&& bright yellow\cr
		\+&\hfill 15&& bright white\cr
}}
\endtable
	Color values~ 1--3 are the foreground, and two color mappings
	or ``palettes'' are available. By default, palette 1 is
	active, but it may be
	changed with the \itwd g_setpal function with the following
	results:
\begintable
\centerline{\vbox{%
  \settabs\+&\it color&\it value\quad &background\quad&\cr
  \+&\it color value&&$\it palette=0$&$\it palette=1$\cr
  \smallskip
  \+&& 0 &background&background\cr
  \+&& 1 &green&cyan\cr
  \+&& 2 &red&magenta\cr
  \+&& 3 &yellow&white\cr
}}
\endtable

\manhead CGA 640 by 200 two color mode\par

	In this mode, color value~0 is the background and is always
	displayed as black. Color value~1 is the foreground and has
	a default color of white. This may be changed, however, with
	the \itwd g_setpal function to any of the colors listed as
	a CGA background color in the previous section.

\manhead EGA sixteen color mode\par

	The EGA has 64 displayable colors,
	16 of which can be displayed at any time. The displayable
	colors are represented as a six-bit value with format
	rgbRGB, where the intensities of of the primary colors
	(red, green, and blue) are in the range 0--3 and represented
	as the two-bit values Rr, Gg, and Bb. The mapping of color
	values to these colors can be changed using the \itwd g_setpal
	function (or \itwd g_setback for color value~0). The default mapping
	is as follows:
\begintable
\centerline{\vbox{%
  \settabs\+&\it color &\it value\quad&bright yellow\quad&\it six-bit &\cr
  \+&\it color value&&\it color&\it six-bit value\cr
  \smallskip
  \+&\hfill 0&&black&\hfill 0&\cr
  \+&\hfill 1&&blue&\hfill 1&\cr
  \+&\hfill 2&&green&\hfill 2&\cr
  \+&\hfill 3&&cyan&\hfill 3&\cr
  \+&\hfill 4&&red&\hfill 4&\cr
  \+&\hfill 5&&purple&\hfill 5&\cr
  \+&\hfill 6&&brown&\hfill 20&\cr
  \+&\hfill 7&&white&\hfill 7&\cr
  \+&\hfill 8&&grey&\hfill 56&\cr
  \+&\hfill 9&&bright blue&\hfill 57&\cr
  \+&\hfill 10&&bright green&\hfill 58&\cr
  \+&\hfill 11&&bright cyan&\hfill 59&\cr
  \+&\hfill 12&&bright red&\hfill 60&\cr
  \+&\hfill 13&&bright purple&\hfill 61&\cr
  \+&\hfill 14&&bright yellow&\hfill 62&\cr
  \+&\hfill 15&&bright white&\hfill 63&\cr
}}
\endtable

\mansee
	intro(1), g_setback(1), g_setpal(1).
\manpend

\manpage g_box(1)

\manname
	g_box --- draw a rectangular box
\mansyn
	void g_box(x1, y1, x2, y2, color)

	int x1, y1, x2, y2;
	unsigned color;
\mandscr
	The \itwd g_box function draws the rectangular box
	 defined by the points
	\itpnt (x1, y1) and \itpnt (x2, y2) in the current drawing buffer
        with color~\itnc color . If xor mode is on, the rectangle will be
	logically xor'ed with the existing data in the buffer.
\mansee
	g_line(1).
\manpend

\manpage g_circle(1)

\manname
	g_circle --- draw a circle
\mansyn
	void g_circle(x, y, r, color)

	int x, y, r;
	unsigned color;
\mandscr
	The \itwd g_circle function draws a circle centered on the point
	\itpnt (x, y) with radius~\itnc r . The circle is drawn in the
	current drawing buffer with color~\itnc color . If xor mode is
	on, the circle is logically xor'ed with the existing data in the
	buffer. The radius is taken to be half of the horizontal diameter
	of the circle, in pixels (because of the graphics display's
	aspect ratio, this will not in general be the same as the vertical
	radius of the circle).
\mansee
	g_ellipse(1).
\manpend

\manpage g_clear(1)

\manname
	g_clear --- clear the area within the clipping boundary to a
	given color
\mansyn
	void g_clear(color)

	unsigned color;
\mandscr
	The \itwd g_clear function sets all the pixels within the current
	clipping boundary in the current drawing buffer to color \itnc color .
\mansee
	g_clearall(1), g_regfill(1), g_setclip(1).
\manpend

\manpage g_clearall(1)

\manname
	g_clearall --- clear an entire buffer to a specified color
\mansyn
	void g_clearall(color)

	unsigned color;
\mandscr
	The \itwd g_clearall function sets the entire current drawing buffer
	to color~\itnc color , regardless of clipping boundaries. For
	clearing the entire screen, \itwd g_clearall should be
	somewhat faster than \itnc g_clear .
\mansee
	g_clear(1).
\manpend

\manpage g_close(1)

\manname
	g_close --- terminate graphics drawing
\mansyn
	void g_close()
\mandscr
	The \itwd g_close function terminates graphics drawing and
	resets the display to 80-column text mode.
\mansee
	g_init(1), g_open(1).
\manpend

\manpage g_ellipse(1)

\manname
	g_ellipse --- draw an ellipse
\mansyn
	void g_ellipse(x, y, r_sub_m, aspect, color)

	int x, y, r_sub_m;
	float aspect;
	unsigned color;
\mandscr
	The \itwd g_ellipse function draws an ellipse in the current
	drawing buffer
	with color~\itwd color centered on the point~\itpnt (x, y) with
	semi-major axis length~\itwd r_sub_m and aspect ratio~\itnc aspect .
	The aspect ratio is defined as the ratio of the vertical diameter
	of the ellipse to its horizontal diameter, and the semi-major
	axis length is half the length of the largest diameter (which
	is vertical if $ aspect > 1.0 $ and horizontal if $ aspect < 1.0 $).
	If xor mode is on, the ellipse will be logically xor'ed with the
	existing data in the buffer.
	Note that this routine can only be used to draw ellipses that have
	their axes oriented horizontally and vertically.
\manbugs
	The aspect ratio of the screen is not accounted for in this
	routine. If you want to have an ellipse drawn in the same
	shape on all supported displays, get the display's aspect
	ratio with the \itwd g_info call and multiply your desired
	aspect ratio by it before passing it to \itnc g_ellipse .
\mansee
	g_circle(1), g_info(1).
\manpend

\manpage g_info

\manname
	g_info --- get information about the graphics device in use
\mansyn
	void g_info(info)

	struct g_info *info;
\mandscr
	The \itwd g_info function copies parameters for the current mode
	and adapter
	into the structure~\itnc info . The \itwd g_info structure
	is defined in the file \bfwd graf.h as:
\mancodebeg
	  struct g_info {
	    unsigned card;
	    unsigned display;
	    unsigned xsize, ysize;
	    unsigned xchsize, ychsize;
	    unsigned colormax;
	    unsigned pages;
	    unsigned curpage;
	  };
\mancodeend
	\itwd Card and \itwd display contain the current types of
	the graphics card and the graphics display, respectively
	(the types are defined in \bfwdn graf.h ). \itwd Xsize
	and \itwd ysize contain the X and Y sizes of the display,
	\itwd xchsize and \itwd ychsize contain the size of the
	screen in characters, and
	\itwd colormax contains the maximum color value (i.e., if
	there are four colors, \itwd colormax will be 3). \itwd Pages
	contains the number of displayable pages that the graphics adapter
	supports and \itwd curpage contains the page that is currently
	being displayed.

	\itwd G_info must be called \itwd after the display is
	opened with \itnc g_open .
\mansee
	g_init(1), g_open(1).
\manpend


\manname
	g_init --- initialize the graphics library
\mansyn
	void g_init(card, display)

	unsigned card, display;
\mandscr
	The \itwd g_init function initializes the graphics library for
	the graphics card and display in use. If \itwd g_init is called
	with \itwd card set to zero, it will attempt to determine
	what graphics hardware is attached. The \itwd display parameter
	is ignored in this case and may be omitted. If \itwd card is
	one of the (nonzero) symbolic constants for graphics adapters
	defined in \bfnc graf.h , the graphics library assumes that
	that card is attached. In this case, the parameter~\itwd display
	must also be specified as one of the symbolic constants defined
	in \bfnc graf.h .

	This function must be called before any others.
\mansee
	g_open(1), g_close(1), g_info(1).
\manpend

\manpage g_line(1)

\manname
	g_line --- draw a line
\mansyn
	void g_line(x1, y1, x2, y2, color)

	int x1, y1, x2, y2;
	unsigned color;
\mandscr
	The \itwd g_line function draws a line in the current drawing
	buffer with color~\itwd color between the points \itpnt (x1, y1)
	and~\itpnt (x2, y2). If xor mode is on, the line is logically
	xor'ed with the existing data in the buffer.
\mansee
	g_box(1), g_point(1).
\manpend

\manpage g_open(1)

\manname
	g_open --- turn on graphics mode and prepare for drawing
\mansyn
	void g_open(mode)

	unsigned mode;
\mandscr
	The \itwd g_open function switches the display to a graphics
	mode and prepares the graphics routines for drawing. The
	interpretation of the \itwd mode parameter is device-dependent.
	Currently, on the CGA, \hbox{mode = CGA_640} is the 640 by 200
	two color
	mode, and \hbox{mode = CGA_320} is the 320 by 200 four color mode.
	The \itwd CGA_640 and \itwd CGA_320 constants are defined
	in \bfnc graf.h . On the
	EGA, the \itwd mode parameter is ignored, and the display
	is opened in the 640 by 350 sixteen color mode using the
	Enhanced Color Display, the 640 by 200 sixteen color mode
	using the Color Display, and the 640 by 350 monochrome
	mode using the Monochrome Display. To use an EGA in a
	CGA mode, pass CGA as the \itwd card parameter to \itnc g_init .

	Besides setting the graphics mode, the \itwd g_open function
	also clears the screen, resets the color mapping to the default,
	turns off xor mode and screen buffering, and resets the
	clipping boundaries to the physical boundaries of the screen.

	This function must be called after \itnc g_init , and before
	any other graphics functions.
\mansee
	g_init(1), g_close(1), g_info(1).
\manpend

\manpage g_point(1)

\manname
	g_point --- plot a point
\mansyn
	void g_point(x, y, color)

	int x, y;
	unsigned color;
\mandscr
	The \itwd g_point function sets the point~\itpnt (x, y) in the
	current drawing buffer to color~\itnc color . If xor mode is on,
	the point is xor'ed with the existing data in the buffer.
\mansee
	g_line(1).
\manpend

\manpage g_regfill(1)

\manname
	g_regfill --- fill a rectangular region with a color
\mansyn
	void g_regfill(x1, y1, x2, y2, color)

	int x1, y1, x2, y2;
	unsigned color;
\mandscr
	The \itwd g_regfill function sets all the points in the current
	drawing buffer within the rectangle defined by the points
	\itpnt (x1, y1) and \itpnt (x2, y2) (and within the current
	clipping boundary) to color~\itnc color .
\manbugs
	Doesn't support xor mode
\mansee
	g_clear(1).
\manpend

\manpage g_setback(1)

\manname
	g_setback --- set the background color
\mansyn
	void g_setback(color)

	unsigned color;
\mandscr
	The \itwd g_setback function changes the color
	displayed for the background color value (0). 

	The actual functioning of this routine depends on the
	graphics mode as follows:

\manhead CGA 640 by 200 two color mode\par

	The \itwd g_setback function
	does not work in this mode.

\manhead CGA 320 by 200 four color mode\par

	The \itwd color parameter should
	be the value of 
	one of the colors listed in the CGA background color table
	on the ``colors(1)'' manual page.

\manhead EGA sixteen color mode\par

	The \itwd color parameter is a six-bit color value
	as discussed on the EGA section in the ``colors(1)'' manual page.
\manbugs
	Doesn't work in the CGA two color mode.
\mansee
	intro(1), colors(1), g_setpal(1).
\manpend

\manpage g_setbuf(1)

\manname
	g_setbuf --- turn on screen buffering
\mansyn
	void g_setbuf(flag)

	unsigned flag;
\mandscr
	The \itwd g_setbuf function turns screen buffering on, if
	\itwd flag is nonzero, or off if \itwd flag is zero.
	When screen buffering is on, drawing takes place in
	an off-screen buffer, instead of in the buffer that is currently
	being displayed. This off-screen buffer can then be made
	visible almost instantaneously with the \itwd g_show function.
	This can be a great help in achieving smooth animation
	and other effects.

	There is, however, one important consideration to keep in
	mind. For effeciency reasons, the \itwd g_show function
	is implemented differently on
	different graphics devices. On the CGA, the drawing is
	done in a single off-screen buffer which is then copied
	to the physical screen buffer when \itwd g_show is
	called. On the EGA, which has two display pages, drawing
	is done in the page that is not visible and the pages are
	swapped when \itwd g_show is called. This means that
	immediately after calling \itwd g_show on a CGA,
	the drawing buffer contains a copy of the image
	being shown on the display. But
	immediately after calling it on an EGA,
	the drawing buffer contains the image that was visible
	just \itncs before it was called. This difficulty
	can be avoided by the simple expedient of erasing the
	active area of the drawing buffer immediately after
	every call to \itnc g_show .
\mansee
	g_show(1).
\manpend

\manpage g_setclip(1)

\manname
	g_setclip --- set the clipping boundaries
\mansyn
	void g_setclip(x1, y1, x2, y2)

	int x1, y1, x2, y2;
\mandscr
	The \itwd g_setclip function restricts drawing
	to the rectangular area defined by the points
	\itpnt (x1, y1) and \itpnt (x2, y2). Points that lie outside
	this rectangle (the ``clipping boundaries'') will be protected
	from change by any the routines that respect the clipping boundaries.
	The clipping boundaries
	cannot be set outside of the physical screen. The functions
	which respect the clipping boundaries are {\it g_box,
	g_circle, g_clear, g_ellipse, g_line, g_point, } and
	\itnc g_regfill .
\manpend

\manpage g_setpal(1)

\manname
	g_setpal --- change the color mapping
\mansyn
	void g_setpal(palette, value)

	unsigned palette, value;
\mandscr
	The \itwd g_setpal function allows one to change the mapping
	between the foreground color values passed to the graphics
	routines and the visible colors actually displayed.

	The actual functioning of this routine depends on the graphics
	mode in use as follows:

\manhead CGA 640 by 200 two color mode\par

	The \itwd g_setpal function
	changes the  color of the foreground color
	value (1). The value of \itwd palette is ignored,
	and \itwd value should be the value of one of the
	colors listed in CGA background color table in the
	``colors(1)'' manual page.
	The visible color of the foreground will be changed to this
	color.

\manhead CGA 320 by 200 four color mode\par

	In this mode, the \itwd value parameter is ignored, and
	\itwd palette should be either 0 or 1.
	The displayed colors are given by the following table:
\begintable
\centerline{\vbox{%
  \settabs\+&\it color&\it value\quad &background\quad&\cr
  \+&\it color value&&$\it palette=0$&$\it palette=1$\cr
  \smallskip
  \+&& 0 &background&background\cr
  \+&& 1 &green&cyan\cr
  \+&& 2 &red&magenta\cr
  \+&& 3 &yellow&white\cr
}}
\endtable

\manhead EGA sixteen color mode\par

	 In this mode, the \itwd g_setpal function
	directly sets the visible color of the color value given
	by \itwd palette to \itnc value , which is a six-bit
	color as discussed in the EGA section of the ``colors(1)''
	manual page.
\mansee
	intro(1), colors(1), g_setback(1).
\manpend


\manpage g_setxor(1)

\manname
	g_setxor --- turn xor mode on or off
\mansyn
	void g_setxor(flag)

	unsigned flag;
\mandscr
	The \itwd g_setxor function turns xor mode on if~\itwd flag
	is nonzero, or off if~\itwd flag is zero. When xor mode is
	off, drawn objects are simply written over existing data in
	the drawing buffer. But if xor mode is on, drawn objects
	are logically xor'ed with the existing data. Thus if an object
	is drawn twice in a row in exactly the same position with xor
	mode on, it will be completely erased after the second
	drawing and the image on the
	screen restored to its state previous to the first drawing.
	This makes xor mode useful for animation and other effects.
	Functions which support xor mode are {\it g_box, g_circle,
	g_ellipse, g_line,} and \itnc g_point .
\manpend

\manpage g_show(1)

\manname
	g_show --- make the drawing buffer visible
\mansyn
	void g_show()
\mandscr
	If screen buffering is on, the \itwd g_show function makes
	the drawing buffer visible by either copying it to the
	physical screen buffer (on adapters with only one page) or
	swapping it with the currently visible page (on adapters
	with more than one page). If screen buffering is off,
	\itwd g_show does nothing.

	See the description of the \itwd g_setbuf function for
	further discussion of screen buffering.
\mansee
	g_setbuf(1).
\manpend

\manpage g_writech(1)

\manname
	g_writech --- write a character
\mansyn
	void g_writech(row, col, ch, color, page)

	unsigned row, col;
	char ch;
	unsigned color;
	int page;
\mandscr
	The \itwd g_writech function writes the single character~\itwd ch
	at character position~\itpnt (row, col) with color~\itnc color .
	If~\itwd page is $-$1, the character is written to the current
	drawing buffer; otherwise it is written to page~\itwd page
	(note: this is not supported with the CGA, as it only
	has one page).
\manbugs
	With the CGA adapter, the \itwd page parameter is ignored.

	Xor mode is not supported.

	Clipping boundaries are not respected.
\mansee
	g_writestr(1).
\manpend

\manpage g_writestr(1)

\manname
	g_writestr --- write a string teletype style
\mansyn
	void g_writestr(row, col, s, color, page)

	unsigned row, col;
	char *s;
	unsigned color;
	int page;
\mandscr
	The \itwd g_writestr writes the null-terminated string
	pointed to by~\itwd s starting at character position
	\itpnt (row, col) with color~\itnc color . 
	If~\itwd page is $-$1, the character is written to the current
	drawing buffer; otherwise it is written to page~\itwd page
	(note: this is not supported with the CGA, as it only
	has one page).

	The characters are written from left to right, top to bottom.
	If the writing goes off the right edge of the screen, it
	continues at the beginning of the next line. If the
	writing goes off the bottom of the screen, the function is aborted.

	The only special characters recognized are newline (octal
	12), which causes the writing to wrap around to the beginning
	of the next line, and carriage return (octal 15) which
	is simply ignored.
\manbugs
	With the CGA adapter, the \itwd page parameter is ignored.

	Xor mode is not supported.

	Clipping boundaries are not respected.
\mansee
	g_writech(1).
\manpend


